\input macros
\def\bookline{\CLOS\  Specification}
\def\chapline{Functions in the Programmer Interface}

\beginChapter 2.{Common Lisp Object System Specification}%
{Functions in the Programmer Interface}{Functions in the Programmer Interface}

Contributors to this document include Daniel G. Bobrow, Linda G.
DeMichiel,\break Richard P. Gabriel, Kenneth Kahn, Sonya E. Keene,
Gregor Kiczales, Larry\break Masinter, David A. Moon, Mark Stefik, and
Daniel L. Weinreb.

Comments and suggestions on this document are encouraged.
Changes will be incorporated over the next several months.
This text will be made available to the X3J13 Committee for the
Common Lisp Standards effort.

\endTitlePage

\beginSection{Introduction}

This chapter describes each of the functions provided by the \CLOS\
Programmer Interface.    The Programmer Interface comprises the set of 
functions that are sufficient for writing most object-oriented
programs.  

The description of each function includes its purpose, its syntax, the
semantics of its arguments and returned values, and often an example
and cross-references to related functions.  This chapter is reference
material that requires an understanding of the basic concepts of the 
Common Lisp Object System.  The functions are arranged in alphabetic 
order for convenient reference.  

The Programmer Interface is distinct from the Meta-Object Protocol.
The Meta-Object Protocol is provided so that systems designers can
experiment with other object-oriented paradigms, for example, using 
different rules of inheritance.   

\vfill
\endSection%{Introduction}


\begincom{add-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf add-method} adds a method to a generic
function and returns the modified generic function as its result.

\label Syntax:

\Defgen {add-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument is one of the following:  a
generic function object; a symbol that names a generic function; or a
list that names a {\bf setf} generic function, such 
as ({\bf setf} {\it symbol\/}). If there is no such generic function, 
an error is signalled.  

The {\it method\/} argument is a method object.  The argument list of
the method function must be congruent with the argument lists of any
other methods associated with the generic function and with the
lambda list of the generic function.
%[i.e., if there are no other methods, then a defgeneric or
%make-generic must have been performed.  better way to say this?]

\label Values:

{\bf add-method} returns the modified generic function, which is the 
same object that was specified by the {\it generic-function\/} 
argument.  

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the given method is already one of the methods of the generic
function or if the method corresponds in parameter specializers and
method qualifiers to an existing method of the generic
function, an error is signalled.

%Note that a given method may be a method on more than one generic
%function.

\label See Also:

{\bf defmethod

make-method

make-generic-function

defgeneric-options}

\endcom


%\begincom{argument-precedence-order}\ftype{Generic function}
%
%\label Purpose:
%
%The generic function {\bf argument-precedence-order} returns an
%association list.  Each pair in this association list consists of
%a parameter name and an integer that indicates the position of the
%corresponding argument in the precedence order.  A value of 0
%indicates the highest precedence.
%
%\label Syntax:
%
%\Defgen {argument-precedence-order} {generic-function}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is a generic function or a symbol
%that names a generic function.
%
%\label Values:
%
%The result is an association list whose pairs consist of a parameter name
%and an integer that indicates the precedence of the corresponding argument.
%
%\label Examples:
%
%\screen!
%
%[To be written.]
%\endscreen!
%
%\endcom


\begincom{call-next-method}\ftype{Macro}

\label Purpose:

The macro {\bf call-next-method} is used within the body of a method.
It calls the ``next method'' with the same arguments that the current
method received, and returns the value or values returned by the method 
it calls.  If there is no next method an error is signalled. 

The type of method combination in use determines in which kinds of
methods {\bf call-next-method} can be used.  The standard method
combination type allows {\bf call-next-method} to be used within primary
methods and {\bf :around} methods, and defines the next method as
follows:  if {\bf call-next-method} is used in an {\bf :around} method,
the next method is the next most specific {\bf :around} method if one is
applicable, otherwise it is the next most specific primary method.  If 
{\bf call-next-method} is used in a primary method, the next method is
the next most specific primary method.

%  [The definition of ``next method'' should
% be given in this sentence and the next paragraph deleted.]
%[I did that. --Sonya]

% [so this provides a general imperative form of method combination.] 
%  [I would omit this sentence--what is {\it imperative\/} method combination?]
% [I omitted it.   I believe Imperative means that in the method 
%itself you control the method combination, by imperatively commanding
%that the next method be called.   This is different than declarative
%method combination, which means that elsewhere you declare, or define,  
%a general framework of how methods will be combined.   -Sonya] 
 
\label Syntax:

\Defmac {call-next-method} {}

\label Arguments:

The macro {\bf call-next-method} is used with no arguments.

\label Values:

The macro {\bf call-next-method} returns the value or values
returned by the method it calls.  

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

{\bf call-next-method} passes the current method's original arguments
along to the next method.  Neither argument defaulting, nor the use of
{\bf setq} or {\bf let} on variables with the same names as parameters,
affects {\bf call-next-method}.
% [??]

Further computation after {\bf call-next-method} returns is possible.

If you define a new type of method combination using the short form of
{\bf define-method-combination}, {\bf call-next-method} can be done in
{\bf :around} methods only. 

Possible extensions: % [have we discussed any of this ?]

{\bf call-next-method} {\it arguments\/}  When at least one argument is
given, {\bf call-next-method} supplies those
arguments instead of the arguments that this method received.  

{\bf apply-next-method} {\it arguments\/} This is like {\bf
call-next-method} except that it uses {\bf apply} instead of {\bf
funcall}.  That is, the last argument is really a list of arguments.

%\label See Also:

See the sections ``Method Selection and Combination'', 
``Standard Method Combination'', and ``Declarative Method Combination''. 

\endcom



\begincom{change-class}\ftype{Function}

\label Purpose:

The function {\bf change-class} changes the class of an instance to a 
new class.  It destructively modifies and returns the instance.

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument is any object.

The {\it new-class\/} argument is a class object or a symbol that names
a class. 

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

All objects are not required to allow {\bf change-class}.   For example,
an implementation is not required to support {\bf change-class} on any
instance of {\bf standard-type-class}.  However, implementations can choose to 
support {\bf change-class} on such objects if is desired.

[The internal protocol of {\bf change-class} needs to be spec'd.]

[We need to document the restrictions of using {\bf change-class}.]

[The function {\bf change-class} currently supports changing the class 
only of instances of metaclass {\bf class}.  The internal protocol of
{\bf change-class} will provide for extensions to other metaclasses.]

\endcom



\begincom{class-of}\ftype{Function}

\label Purpose:

The function {\bf class-of} returns the class object for the most
specific class of which the given object is an instance.  Every Common
Lisp object has a class.

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:

The function {\bf class-of} returns the class object that represents the
most specific class of which the  argument is an instance.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the object was created with a constructor defined by {\bf defstruct}, 
the class that is returned is the class with the same name as the data
type defined with the {\bf defstruct} form.

If the object is an instance of a class whose class is {\bf
standard-type-class} or a subclass of {\bf standard-type-class} (other 
than a class created with {\bf defstruct}), the class that is returned
is the most specific class according to Figure~1-2.

%Note that {\bf class-of} can never return an abstract class.
%We did away with abstract classes.  -Sonya

\endcom



\begincom{defclass}\ftype{Macro}

\label Purpose:

The macro {\bf defclass} defines a new class.  It returns the name of
the new class as its result.

The syntax of {\bf defclass} provides options for specifying default
initialization values for slots and for requesting that functions be
automatically generated to read and write the values of slots and to
construct new instances.  No accessor, reader, or constructor
functions are defined by default; their generation must be explicitly 
requested.  No initial slot values are provided by default. 

Defining a new class also causes a type of the same name to be defined. 
The predicate {\tt (typep {\it object class-name\/})} is true if the
class of the given object is {\it class-name\/} itself, or any component
of the class {\it class-name\/}.   

\eject
\label Syntax:

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name} \paren{\star{\curly{superclass-name}}}
\paren{\star{\curly{slot-spec}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it superclass-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-spec\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \star{\curly{slot-option}})\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :accessor} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :reader} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type\/} $\vert$ \cr
\+&&{\tt :initform} {\it form\/} $\vert$ \cr
\+&&{\tt :type} {\it type-specifier\/} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic $\vert$ :none}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessor-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :reader-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol\/} \brac{boa-arglist\/}) $\vert$\cr
\+&&({\tt :documentation} {\it string\/}) $\vert$ \cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform}{\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject


\label Arguments:

The {\it class-name\/} argument is a non-{\bf nil} symbol.  It becomes the 
name of the new class.  If a class with the same name already exists, the
definition of that class is replaced.

Each {\it superclass-name\/} argument is a non-{\bf nil} symbol.
The new class will inherit slots and methods from each of its superclasses,
from their superclasses, and so on.
% characteristics (such as slots) and behavior (such as 
% methods) from each of its superclasses (and from their superclasses).

Each {\it slot-spec\/} argument is the name of the slot or a list consisting
of the slot name followed by zero or more slot options.  The {\it slot-name\/}
argument is a symbol that can be used as a Common Lisp variable name.

%{\it slot-spec\/} can be a list of the slot name and its {\it
%default-value\/}, which can be any form.  When an instance is made and
%no initial value for this slot is provided as an argument to {\bf
%make-instance}, the slot is initialized to the value of this form.  The
%{\it default-value\/} is evaluated every time it is used. 

The following {\it slot-options\/} are available:

\beginlist

\item{\bull} 
The {\bf :accessor} option specifies that a method is to be
defined on the generic function named {\it generic-function-name\/} to
read the value of the given slot and that a method is to be defined on the
setf generic function named {\it generic-function-name} to be
used with {\bf setf} to modify the value of the slot.
The {\it generic-function-name\/} argument is a non-{\bf nil} symbol.
The {\bf :accessor} option may be specified more than once for a given
slot.

\item{\bull}
The {\bf :reader} option specifies that a method is to be
defined on the generic function named {\it generic-function-name\/}
to read the value of the given slot.  The {\it
generic-function-name\/} argument is a non-{\bf nil} symbol.  The {\bf
:reader} option may be specified more than once for a given slot.

\item{\bull}
The {\bf :allocation} option is used to specify where storage is to be
allocated for the given slot.  Storage for a slot may be static or dynamic;
it may be located in the class instance or in the class object itself.
The value of the {\it allocation-type\/}
argument can be one of the following keywords: {\bf :instance}, {\bf :class},
{\bf :dynamic}, or {\bf :none}.  The {\bf :allocation} option may be
specified at most once for a given slot.  If the {\bf :allocation} option
is not specified, storage for the slot is allocated in the class instance.

\beginlist

\itemitem{--}
If the allocation type is {\bf :instance}, storage for the slot is allocated
in each instance of the class.  

\itemitem{--}
If the allocation type is {\bf :class}, storage for the slot is allocated
in the class object created by the {\bf defclass} form.  The value of
the slot is shared by all instances of the class.  Any subclass of this
class will share this single slot unless the {\bf defclass} form 
for that subclass specifies a slot of the same name.  

%[The useful part of this paragraph should go elsewhere--in the concepts
%document.]
%{\bf :allocation :class} Storage is allocated in the class.  Thus a
%single value for this slot is shared by all instances.  Class slots
%(like other slots) are inherited by subclasses of this class.  The state
%associated with a class slot is stored only where it is explicitly
%specified in the class.  If a local description of a slot is provided,
%it completely overrides an inherited description of a component class. 
 
\itemitem{--}
If the allocation type is {\bf :dynamic}, storage is allocated in the instance
the first time the slot is used.  This option allows infrequently-used slots
to occupy storage only if necessary.
%If the slot is initialized with a keyword
%argument to {\bf make-instance}, the slot is allocated then.  If the
%first access is a read, then storage is allocated and the default value
%specified in the {\bf defclass} form, if any, is stored in the slot and
%returned.  If the first access is a {\bf setf}, then storage is
%allocated and the value is stored in the slot and returned.  

\itemitem{--}
If the allocation type is {\bf :none}, no storage is allocated for the
slot and the slot will not exist in instances of the given class.  This
option may be used to override the inheritance of slots defined by
a superclass.

\endlist 

\item{\bull}
The {\bf :initform} option is used to provide
an initial value form to be used in the initialization of the
slot.  The {\bf :initform} option may be specified at most once for a
given slot.    This form is evaluated every time it is used.  
It is important to specify both the lexical and dynamic environment in which
this form is evaluated. 
The lexical environment in which this form is evaluated is the 
lexical environment in which {\bf defclass} was evaluated.
Note that the lexical environment refers both to variables and to functions. 
The dynamic environment is the one in effect at the time the form is evaluated.
This is the same behavior specified in {\it Common Lisp the Language\/} 
for {\bf defstruct} slot initialization forms. 

%I removed this according to the mail.  -Sonya
%If we put it back in, the Syntax line for it was:
%\+&&{\tt :initialize-only} {\it flag\/} $\vert$\cr
%Also, must decide if it be given more than once per slot, or not?
%\item{\bull}
%The {\bf :initialize-only} option is used to specify that the contents
%of the given slot may not be altered after the instance is created.
%The default value of the {\bf :initialize-only} option is {\bf nil}.

\item{\bull}
The {\bf :type} option specifies the type of the slot contents.  The
argument to {\bf :type} is a type specifier.  If the {\bf :type}
option is specified, the slot contents must be of the given type.
The {\bf :type} option may be specified at most once for a given slot. 

%\item{\bull}
%The {\bf :initable} option specifies a non-{\bf nil} symbol to be used
%to specify an initial value of this slot, when a new instance is being
%made.  This symbol can be supplied as an {bf \&key} argument to {bf
%make-instance}.  (This is still under discussion.) 
%The {\bf :initable} option may be specified more than once for a given slot.

\endlist

Each {\it class-option\/} is an option that refers to the class as a whole
or to all class slots.
The following options are available:

\beginlist
\item{\bull}
The {\bf :accessor-prefix} option specifies that, for each
slot, a method to read the value of the slot is to be defined on the 
generic function named {\it string-or-symbol}{\bf -} followed by the
name of the slot.  Similarly, a method to be used with the macro {\bf
setf} to modify the value of the slot is to be defined on the setf
generic function named {\it string-or-symbol}{\bf -} followed by the
name of the slot.  These accessor functions are interned in the
package that is current at the time the {\bf defclass} form is
macro-expanded.  If the prefix is {\bf nil}, the names of the accessor
functions are the symbols that are used as the slot names.  The {\bf
:accessor-prefix} option may be specified more than once.

\item{\bull} 
The {\bf :reader-prefix} option specifies that,
for each slot, a method to read the value of the slot is to be defined
on the generic function named {\it string-or-symbol}{\bf -} followed by
the name of the slot.  These reader functions are interned in the
package that is current at the time the {\bf defclass} form is
macro-expanded.  If the prefix is {\bf nil}, the names of the reader
functions are the symbols that are used as the slot names.  The {\bf
:reader-prefix} option may be specified more than once.

\item{\bull}
The {\bf :constructor} option causes a constructor function to be
generated automatically.  The constructor function is used to make
new instances of the class.
The {\it symbol\/} argument is a non-{\bf nil} symbol that
specifies the name of the constructor function.
If the {\it boa-arglist\/} argument is present, it describes the arguments
to the constructor.  The {\it boa-arglist\/} argument of {\bf defclass}
is the same as that of {\bf defstruct}, with some additions.   Here,
{\bf \&key} and {\bf \&allow-other-keys} are allowed, as are supplied-p
parameters. 
%In the simplest case, the elements of {\it arglist\/} are the slot
%names themselves ({\it not\/} keywords) in the order in which they are to
%occur as arguments.  The keywords {\bf \&optional}, {\bf \&rest}, and
%{\bf \&aux} may also be used in {\it arglist\/}.  Any {\bf \&optional} and
%{\bf \&aux} arguments for which no initialization forms have been specified
%in {\it arglist\/} are not set to {\bf nil} as they would be in a lambda list.
%The initial value of any {\bf \&optional} argument for which no initialization
%form is specified in {\it arglist\/} is taken from the
%{\it initform\/} argument given for the slot description.  The initial value
%of any {\bf \&aux} argument for which no initialization form is specified in
%{\it arglist\/} is undefined.
The {\bf :constructor} option may be specified more than once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :default-init-plist} option is used to specify default values
%that are to be used when making an instance of the class.  For
%example, a class might specify a default value to use to initialize a

%must be a valid keyword argument to {\bf make-instance}.  Each {\it
%argument\/} is a form that provides the default value for that keyword
%argument if it is not supplied.  The user can override the defaults in
%the {\bf :default-init-plist} by providing keyword arguments to {\bf
%make-instance}.  The {\it arguments\/} are evaluated every time they
%are used.  The {\bf :default-init-plist} option may be specified more
%than once.  This option is still under discussion; it is not yet clear
%whether it should be in the standard.

\item{\bull} 
A documentation string may be attached to the class name
by specifying the {\bf :documentation} argument.  The documentation
type for this string is {\bf type}.  The form {\tt (documentation {\it
class-name\/} 'type)} may be used to retrieve the documentation
string.  The {\bf :documentation} option may be specified at most once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :init-keywords} option is used to
%specify that the given keywords may be used as keyword arguments to
%{\bf make-instance} when an instance of this class is to be created.
%It is not necessary to provide this argument to make it possible
%to initialize slots; that is done with the {\bf :initable-slots} option.
%The {\bf :init-keywords} option is used in conjunction with user-supplied
%methods {\bf make-instance}.  If a {\bf make-instance} method accepts
%an argument, it must be made an allowed keyword argument to {\bf make-instance}
%by using this option.
%The {\bf :init-keywords} option may be specified more than once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :initable-slots} option is used to specify that it is allowed
%to initialize all
%slots of this class.  The initialization can be done by providing the
%keyword with the same name as the slot, followed by the slot's initial
%value as an argument to {\bf make-instance} or by including the keyword
%and value in the {\bf :default-init-plist}.

%\item{\bull}
%[Omitted because both Moon and Gregor thought it ought to go.  -Sonya]
%The {\bf :uninstantiable} option is used to specify whether it is
%possible to directly instantiate the new class with {\bf make-instance}.
%If the value of {\bf :uninstantiable} is true, the class cannot be instantiated
%and is termed an {\bit abstract class}.  The default value of {\bf
%:uninstantiable} is {\bf nil}.  The {\bf :uninstantiable} option may be 
%specified at most once.

\item{\bull}
The {\bf :metaclass} option is used to specify that instances of this 
class should have a different metaclass than the default provided by the
system (the class {\bf class}).  The {\it class-name} argument is the
name of the desired metaclass.  The {\bf :metaclass} option may be 
specified at most once. 

%\item{\bull}
%The {\bf :predicate} option causes a predicate function
%named {\it symbol\/} to be generated automatically.  The {\it
%symbol\/} argument must be a non-{\bf nil} symbol.  The predicate
%function takes one argument, an object.  It returns true if the object
%is of this class, otherwise it returns {\bf nil}.  The {\bf :predicate}
%option may be specified more than once.

\endlist

\label Values:

The name of the new class is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If a class of the same name already exists, that class is redefined as 
follows:

\beginlist
\item{\bull}
A copy of the class object is created.  This copy is named {\tt
|obsolete-{\it class-name\/}|}, where {\it class-name\/} is the name of
the original class; this copy is {\bf equal} to the original class
object.

\item{\bull}
 All instances of the original class are made to point to the
``obsolete'' class object.

\item{\bull}
The original class object is modified to reflect the specified
changes; this modified class object is {\bf eq} to the original.

\item{\bull}
When an instance of the obsolete class 
is accessed, it is updated to reflect the new class definition.

\endlist

It is not allowed to redefine a {\bf standard-type-class}.  

Each class has a superclasses lattice composed of all its immediate
superclasses, the immediate superclasses of these superclasses, and so
on.  This lattice is used to compute the class precedence list of the
class.  It is discussed in the section ``Determining the Class
Precedence List.''

Note the following rules of {\bf defclass}:

\beginlist

\item{\bull}
It is not required that the superclasses of a class be defined before
the {\bf defclass} form for that class is evaluated.

\item{\bull}
All the superclasses of a class must be defined before it is permitted
to make an instance of the class.

\item{\bull}
A class must be defined before it can be used as a parameter
specializer in a {\bf defmethod} form.

\item{\bull}
All the superclasses of a class must be defined before it is
permitted to evaluate or compile a {\bf with-slots} that uses that class.

\endlist


Slot options and class options are inherited by a class from its
superclasses.   However, it is possible to override an option
that would be inherited from a superclass simply by specifying
that option in the {\bf defclass} form.  [This needs to be made more
precise.]

Some implementations might add other options to {\bf defclass}.
Therefore it is required that all implementations signal an error if
they observe a class option or a slot option that is not implemented
locally.

If no default value for a slot is specified either in a {\bf
defclass} or a {\bf make-instance} form, the initial value of the
slot is unspecified.

It is valid to specify more than one accessor, reader, and initialization
keyword for a slot.

If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value} or {\bf
with-slots} using {\bf :use-accessors nil}.

The {\bf :accessor} and {\bf :reader} slot options may appear more than once.

The {\bf :accessor-prefix}, {\bf :constructor}, and {\bf :reader-prefix}
class options may appear more than once.  No other class option may 
appear more than once in a single {\bf defclass} form.  No other slot 
option may appear more than once in a single slot description. 

\label See Also:

{\bf slot-value

with-slots}

\endcom



\begincom{defgeneric-options}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric-options} is used to specify options and
declarations that pertain to a generic function as a whole.

The generic function is stored in the symbol-function cell of {\it name}.
If {\tt (fboundp {\it name\/})} is {\bf nil}, a new generic function 
is created.  If {\tt (symbol-function {\it name\/})} is a generic function,
that generic function is modified.  If neither of these conditions holds,
{\bf defgeneric-options} signals an error.

The macro {\bf defgeneric-options} returns {\it name\/} as its result.

\label Syntax:

\Defmac {defgeneric-options} {name lambda-list \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it
parameter-names\/}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} {\it args\/}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}

\label Arguments:

The {\it name} argument is a non-{\bf nil} symbol.

The {\it lambda-list\/} argument is an ordinary function lambda list
with these exceptions:

\beginlist
\item{\bull}
No {\bf \&aux} variables are allowed. 

\item{\bull}
Optional and keyword arguments may not have default initial value forms
or use supplied-p parameters.
The generic function passes to the method all the argument values passed to
it and only those; default values are not supported.
Note that optional and keyword arguments in method definitions, however,
can have default initial value forms and can use supplied-p parameters. 
\endlist

The following options are provided:

\beginlist

\item{\bull}
The {\bf:argument-precedence-order} option is used to specify the
order in which the required arguments in a call to the generic
function are tested for specificity when selecting a particular
method.  By default, all required arguments are considered from left
to right; each required argument has precedence over those to its
right.   Each required argument should be included as a {\it
parameter-name}, so the full and unambiguous precedence order is
supplied.   If this condition is not met an error is signalled.
%The {\it argument-precedence-alist} argument is an association
%list.  Each pair in this association list consists of a parameter name
%and an integer (greater than or equal to 0 and less than the number of
%required arguments) that indicates the position of the corresponding
%argument in the precedence order.  A value of 0 indicates the highest
%precedence.  A full and unambiguous precedence order must be supplied
%or an error is signalled.

\item{\bull}
The {\bf declare} option is used to specify declarations that pertain
to the generic function.  These declarations do not apply to the
methods.  The only declaration is this standard is {\bf optimize} which
can have the value of speed or space.   This allows the user to control
whether method selection is optimized for speed or space, but has no
effect on individual methods.  
Declarations that have semantic effect ({\bf special}, {\bf 
inline}, and {\bf notinline} declarations) are not permitted.  Other 
types of declarations are advice to the compiler that may or may not
affect the implementation of the generic function.  Individual
implementations are not required to implement them.  
If an implementation notices a declaration that it does 
not support and that has not been proclaimed as a non-standard
declaration name, it should issue a warning.
It is expected that one use of this facility will be for {\bf ftype}
declarations.   

\item{\bull}
The {\bf :documentation} argument associates a documentation string
with the generic function.   The documentation type for this string
is {\bf function}.  The form
{\tt (documentation {\it generic-function-name\/} 'function)}
may be used to retrieve this string.

\item{\bull}
The {\bf :generic-function-class} option may be used to specify that
the generic function is to have a different class than the default provided
by the system (the class {\bf generic-function}).
The {\it class-name\/} argument is the name
of a class that can be the class of a generic function.

%\item{\bull}
%The {\bf :interface} option is still under discussion.
%[The meaning of this stuff isn't clear enough to me for me to be
%able to rewrite it:
%                Defines a function that runs instead of the generic
%                dispatch.  This is completely transparent to anyone calling
%                the generic function.  Such a prologue function can be used
%                to rearrange the arguments, to standardize the arguments
%                before the methods see them, to default optional arguments,
%                to do the shared non-generic portion of an operation, or
%                for any other purpose.
%
%                Inside the forms you can trigger the generic dispatch with
%                (call-next-method args...) or (apply-next-method args...).
%		apply-next-method treats the last argument as a list of
%                arguments just like apply.  ]
%
%\item{\bull}
%(:method-arguments {lambda-list}+)
%[The meaning of this stuff isn't clear enough to me for me to be
%able to rewrite it:
%		This option is under discussion. 
%                You can use this option to specify that the methods accept
%                different arguments than does the generic function itself.
%                By default, the methods receive the same arguments that are
%                specified at the top of the defgeneric form.   If
%		:interface is also specified, it provides the
%		translation from generic-function arguments to 
%		method-arguments.   If :interface is not specified, the
%		arguments are permuted according to matching names, and
%		all names in the :method-arguments lambda-list must also
%		appear in the generic-function's lambda-list.   For
%                example:
%			
%		(defgeneric foo (x y \&optional z) 
%                   (:method-arguments y x z)) ]

\item{\bull}
The {\bf :method-class} option is used to specify that all methods for
this generic function are to have a different class than the default
provided by the system (the class {\bf method}).
The {\it class-name\/} argument is the name of a
class that is capable of being the class of a method.

\item{\bull}
The :method-combination option is followed by a symbol that
names a type of method combination.   The arguments (if any) that follow 
that symbol depend on the type of method combination.   For example, all 
types of method combination defined by the short form of {\bf 
define-method-combination} accept an optional argument named {\it 
order\/}, defaulting to {\bf :most-specific-first}.  A value of {\bf
:most-specific-last} reverses the order of the primary methods, without
affecting the order of the auxiliary methods.

\endlist

\label Values:

The macro {\bf defgeneric-options} returns {\it name\/} as its result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[What happens when {\bf defgeneric-options} causes the options of an existing
generic function to be changed needs to be spec'd out.]

If a {\bf defgeneric-options} form is evaluated and some methods for that
generic function have parameters that are not congruent with those
listed in the {\bf defgeneric-options}, an error is signalled.  
[Note:  other kinds of errors still need to be discussed.]

[Needs discussion about compatibility of methods.]

Some implementations might add other options to {\bf defgeneric-options}. 
Therefore it is required that all implementations signal an error if
they observe an option that is not implemented locally.

\endcom




\begincom{defgeneric-options-setf}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric-options-setf} is used to define a {\bf setf}
generic function.  A {\bf setf} generic function is called in an
expression such as {\tt (setf ({\it name arguments}) {\it new-value})}.

The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.

\label Syntax:

\Defmac {defgeneric-options-setf} {name lambda-list setf-lambda-list \star{\curly{option}}}

{\it setf-lambda-list\/}::$=$ \paren{variable-name\/}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it argument-precedence-alist\/}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} {\it args\/}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip1pc!\null

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol.

The {\it lambda-list\/} argument is identical to the
{\it lambda-list\/} argument of {\bf defgeneric-options}.

The keyword options are the same as for {\bf defgeneric-options}.

\label Values:

The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.

\label Examples:

\screen! 

[To be written.]
\endscreen!

\label Remarks:

[The internal operation of this function needs to be spec'd out.
%--Gregor to provide.
]

[Needs discussion about compatibility of methods.]

\label See Also:

{\bf defgeneric-options

defmethod}

\endcom




\begincom{define-method-combination}\ftype{Macro}

\label Purpose:

The macro {\bf define-method-combination} is used to define new types
of method combination.    The syntax and semantics of {\bf define-method-combination}
are described in ``Declarative Method Combination'', along with several 
examples of its use.

%\label Remarks: 

The following functions are provided as part of the declarative 
method combination facility:

{\bf make-method-call}

{\bf method-qualifiers}

{\bf multiple-value-prog2}

{\bf method-combination-error}

{\bf invalid-method-error} 

\endcom



\begincom{defmethod}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod} defines a new method on a generic
function.

If no generic function is currently named by the symbol {\it name\/}, a
generic function is created with default values for the argument
precedence order (each argument is more specific than the arguments to 
its right in the argument list), the generic function class (the class
{\bf generic-function}), the method class (the class {\bf method}), and
the standard method-combination type.  The lambda list of the 
generic function is congruent with the argument list of the method being
defined.

If the symbol {\it name\/} names a non-generic function an error is 
signalled. 

The argument list of the method must be congruent with the lambda
list of the generic function.  If this condition does not hold, an error is
signalled.  See ``Generic Functions and Methods'' for 
a definition of congruency in this context.  

\label Syntax:

\Defmac {defmethod} {name
\vtop{\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol that
names the generic function on which the method is defined.
%was: the generic function being specialized.   

The {\it method-qualifier\/} is the object that is used
by method combination to identify the given method.  A method
qualifier is a non-{\bf nil} atom.  The precise method
combination type may further restrict what a method qualifier
may be.  [The details of method combination and method
qualifiers are still under discussion.]

The {\it specialized-lambda-list\/} argument is like an ordinary
function lambda list except that parameters for required arguments may
be replaced by specialized parameters.  A specialized parameter is a
list {\tt ({\it variable-name parameter-specializer\/})}.  Only
required parameters may be specialized.
A parameter {\it specializer\/} 
is a symbol that names a user-defined class, a structure defined by
{\bf defstruct} if the {\bf :type} option was not used, or a class
that corresponds to a Common Lisp type specifier.   Note that
not all Common Lisp types have a corresponding
class.   The section ``Generic Functions and Methods''
lists the Common Lisp types that have corresponding
classes.  A parameter specializer can also be {\tt (quote {\it object\/})}.
Such a parameter specializer indicates that this corresponding argument must
be {\bf eql} to the quoted object for the method to be applicable.  
If no parameter specializer is specified for a given required parameter,
the parameter specializer for that parameter defaults to {\bf t}.
A method, all of whose required arguments have {\bf t} parameter 
specifiers is termed a {\bit default method}.  Such a method is selected
when no more specific method for the generic function is applicable.

\label Values:

The result of {\bf defmethod} is the method object.

%Changed by Sonya according to mail from Moon, Gregor, and Danny.
%Used to be the following: 
%The result of {\bf defmethod} is the list consisting of the generic
%function name, a list of the method qualifiers, and a list
%of the lambda list specializers that is equivalent to the value returned
%by {\bf lambda-list-specializers} when applied to the specified lambda
%list.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The class of the method object that is created is that given by the
method class option of the generic function on which the method is defined.

[To be discussed: ``replacing'' or ``redefining'' a method.]

\label See Also:

{\bf get-method

lambda-list-specializers}

\endcom


\begincom{defmethod-setf}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod-setf} defines a method for a {\bf setf} generic
function.  A {\bf setf} generic function is called in an expression such as: 
{\tt (setf ({\it generic-function-name arguments\/}) {\it new-value\/})}. 

\label Syntax:

\Defmac {defmethod-setf} {name
\vtop{\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list specialized-setf-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specialized-setf-lambda-list\/}::$=$ (\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

The arguments {\it name\/}, {\it method-qualifier\/}, and {\it
specialized-lambda-list\/} are the same as for {\bf defmethod}. 

The {\it specialized-setf-lambda-list\/} argument is the same as {\it
specialized-lambda-list\/} except that for now there can be only one
parameter.  In other words, {\it setf-lambda-list\/} is a lambda list
containing exactly one required parameter, which may be specialized.
It is either {\tt ({\it variable-name\/})} or {\tt (({\it variable-name
parameter-specializer\/}))}.  
%[Do we want to clarify this for now stuff?]

The {\it variable-name\/} argument in the {\bf setf} lambda list
is the name of the variable that gets bound to the
value of the {\it new-value\/} form in the expression
{\tt (setf {\it place new-value})}.
 
\label Values:

The result of {\bf defmethod-setf} is the method object.

%Changed by Sonya according to mail from Moon, Gregor, and Danny.
%Used to be the following: 
%The result of {\bf defmethod-setf} is the list consisting of the generic
%function name, a list of the method qualifiers, and list
%of the lambda list specializers that is equivalent to the value returned
%by {\bf lambda-list-specializers} when applied to the specified lambda
%list, and a list of the setf lambda list specializers.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod}

\endcom



\begincom{describe}\ftype{Generic function}

\label Purpose:

The Common Lisp function {\bf describe} is replaced by a generic
function.  {\bf describe} prints information about a given object on the
standard output.

Each implementation is required to provide a default method for {\bf 
describe}; that is, a method for the class {\bf t}.  Implementations  
are free to add methods for specific classes.  Users can write methods  
for {\bf describe} for their own classes if they do not wish to 
inherit an implementation-supplied method. 

%[Changed according to mail by Moon and RPG. -- Sonya]
%Each implementation is required to replace its former implementation of
%{\bf describe} with one or more methods.  In particular, there must
%be methods provided for the classes {\bf t} and {\bf object}.]
%Implementations are free to add methods for other classes.

Users can also write methods for {\bf describe}.  These methods must
conform to the definition of {\bf describe} as specified in {\it
Common Lisp the Language}.

\label Syntax:

\Defgen {describe} {object}

\label Arguments:

The argument of {\bf describe} may be any Common Lisp object. 

\label Values:

The function {\bf describe} returns no values.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{documentation}\ftype{Generic Function}

\label Purpose:

The Common Lisp function {\bf documentation} is replaced by a generic
function.  {\bf documentation} returns the documentation string
associated with the given object if it is available, otherwise 
{\bf nil}. 

%[See Patrick's comments.]

\label Syntax:

\Defgen documentation {x {\opt} doc-type}

\label Arguments:

The first argument is a generic function, a method object, a class
object, or a symbol.   If it is a generic function, it is in one of
these forms: a generic function object; a symbol that names a generic
function; or a list that names a {\bf setf} generic function, such as
({\bf setf} {\it symbol\/}).

If the first argument is a generic function, method object, or class
object, {\bf documentation} returns the documentation string for that
object.

If the first argument is a symbol, the second argument must not be
supplied. 

If the first argument is a symbol, the second argument must be
supplied.  {\bf documentation} returns the documentation string of 
the given type.  The {\it doc-type\/} argument is a symbol.  It can be
one of the following types: {\bf variable}, {\bf function}, {\bf
structure}, {\bf type}, and {\bf setf}.

If no documentation is associated with the given object, {\bf documentation}
returns {\bf nil}.

\label Values:

The documentation string associated with the given object is returned
unless none is available, in which case {\bf documentation} returns
{\bf nil}.

\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function, method, or class.

\endcom



%\begincom{generic-function-lambda-list}\ftype{Generic function}
%
%\label Purpose:
%
%The generic function {\bf generic-function-lambda-list} returns the
%lambda list of its argument from which default values for {\bf
%\&optional} and {\bf \&key} parameters and supplied-p parameters have
%been removed.
%
%\label Syntax:
%
%\Defgen {generic-function-lambda-list} {function-or-generic-function}
%
%\label Arguments:
%
%The argument to {\bf generic-function-lambda-list} is either a
%function, a symbol that names a function, or a generic function.
%If it is a generic function, it is in one of
%these forms: a generic function object; a symbol that names a generic
%function; or a list that names a {\bf setf} generic function, such as
%({\bf setf} {\it symbol\/}).
%
%\label Values:
%
%The result of {\bf generic-function-lambda-list} is a copy of the
%lambda list of its argument from which default values for {\bf
%\&optional} and {\bf \&key} parameters and supplied-p parameters have
%been removed.
%
%\label Examples:
%
%\screen!
%
%[To be written.]
%\endscreen!
%
%\label Remarks:
%
%There is a related function named {\bf function-parameters} that is
%being considered for Common Lisp.
%
%\endcom
%
% 
%\begincom{generic-function-method-combination-type}\ftype{Generic function}
%
%\label Purpose:
%
%The generic function {\bf generic-function-method-combination-type}
%returns the method combination type for the given generic function.
%
%[The details of this function are currently under discussion.]
%
%\label Syntax:
%
%\Defgen {generic-function-method-combination} {generic-function}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is either a generic function
%object; a symbol that names a generic function; or a list that names a
%{\bf setf} generic function, such as ({\bf setf} {\it symbol\/}). 
%
%\label Values:
%
%\label Examples:
%
%\screen!
%
%[To be written.]
%\endscreen!
%
%\endcom


%\begincom{generic-function-p}\ftype{}
%
%\label Purpose:
%
%The predicate {\bf generic-function-p} is true if its argument is a
%generic function, otherwise it is false.
%
%\label Syntax:
%
%\Defun {generic-function-p} {object}
%
%\label Values:
%
%A non-{\bf nil} value is returned if the argument is a generic function
%object, otherwise the result is {\bf nil}.
%
%\label Examples:
%
%\screen!
%\endscreen!
%
%\endcom



\begincom{get-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf get-method} takes a generic function and returns the
method object that has the given method qualifiers and 
parameter specializers.  If no such method exists, {\bf get-method}
signals an error.   

\label Syntax:

\Defgen {get-method} {generic-function method-qualifiers specializers}

\label Arguments:

The {\it generic-function\/} argument is either a generic function 
object; a symbol that names a generic function; or a list that names a
{\bf setf} generic function, such as ({\bf setf} {\it symbol\/}). 
An error is signalled if no such generic function exists, or if the 
symbol given as the first argument names a non-generic function (even if
the {\it specializers\/} argument indicates a request for a default
method; see below). 

The {\it method-qualifiers\/} argument is a list of the
method qualifiers for the method.

The {\it specializers\/} argument is a list of the parameter
specializers for the method.  It must correspond in length to the number
of required arguments of the generic function.  This means that to
obtain the default method for a given generic function, a list of {\bf
t}'s corresponding in length to the number of required arguments of that
generic function must be given.  

%If {\it specializers\/} is {\bf nil}, the
%default method function for that generic function is returned.

\label Values:

The result of {\bf get-method} is the method object with the given
method qualifiers and parameter specializers.  If no such
method object exists, {\bf get-method} signals an error.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{get-setf-generic-function}\ftype{Function}

The function {\bf get-setf-generic-function} takes a symbol for which
a setf generic function has been defined by either {\bf
defmethod-setf} or {\bf defgeneric-options-setf} and returns a generic
function object.  This object is the generic function that is called
when the {\tt (setf ({\it generic-function-name arguments\/})
{\it new-value\/})} is invoked.

[More details to be provided by Gregor.]

\label Syntax:

\Defun {get-setf-generic-function} {name}

\label Arguments:

The {\it name\/} argument is a symbol for which a setf generic
function has been defined.  If no such setf generic function has been
defined, an error is signalled.

\label Values:

The function {\bf get-setf-generic-function} returns a generic function
object. 
This object is the generic function that is called
when the {\tt (setf ({\it generic-function-name arguments\/})
{\it new-value\/})} is invoked.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{invalid-method-error}\ftype{Function}

\label Purpose:

The function {\bf invalid-method-error} reports an applicable method
whose qualifiers are not valid for the method combination type.  The 
error message is constructed using a format string and any arguments to it. 
An implementation may add additional contextual information 
to the error message, thus {\bf invalid-method-error} should be called
only from the dynamic environment of a method-combination function.

The environment determines whether {\bf invalid-method-error} returns to its
caller or throws.

\label Syntax:

\Defun {invalid-method-error} {method format-string {\rest} args}

\label Arguments:

The {\it method\/} argument is the invalid method object.  

{\it format-string\/} is a control string that can be given to {\bf 
format}, and {\it args\/} are any arguments required by the format
string. 

\label Remarks:

The function {\bf invalid-method-error} is called automatically when a
method fails to satisfy every qualifier pattern and predicate in a
{\bf define-method-combination}.
% shouldn't there be a noun after ``a {\bf define-method-combination}''?
A method combination function that
imposes additional restrictions should call {\bf invalid-method-error}
explicitly if it encounters a method it cannot accept.

The function {\bf invalid-method-error} will use the condition
signalling system when and if it is adopted into Common Lisp.

\endcom




%\begincom{lambda-list-specializers}\ftype{Function}
%
%\label Purpose:
%
%The function {\bf lambda-list-specializers} takes an ordinary lambda
%list or a specialized lambda list and returns a list containing the
%parameter specializers for all required arguments.  The specializer
%{\bf t} is returned for any required lambda list argument for which no
%parameter specializer was given.
%
%\label Syntax:
%
%\Defun {lambda-list-specializers} {specialized-lambda-list}
%
%\label Values:
%
%The result of {\bf lambda-list-specializers} is a list of the parameter
%specializers for all required arguments in the given lambda list.
%
%\endcom


\begincom{make-generic-function}\ftype{Function}

\label Purpose:

The function {\bf make-generic-function} creates and returns a generic
function.  This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.

\label Syntax:

\Defun {make-generic-function} {\key \vtop{\hbox{ :lambda-list :argument-precedence-order}
\hbox{ :declare :documentation :method-combination} 
\hbox{ :generic-function-class :method-class}}}

\label Arguments:

The {\bf :lambda-list} argument is a lambda list of the type that may be
given to {\bf defgeneric-options}.   

The following arguments have the same semantics as the corresponding
arguments of {\bf defgeneric-options} although their syntax may differ:

\beginlist

\item{\bull}
The {\bf :argument-precedence-order} argument is an association list.
Each pair in this association list consists of the parameter name of
one of the required parameters (as specified by the {\bf :lambda-list}
argument) and an integer (greater than or equal to 0 and less than the
number of required arguments) that indicates the position of the
corresponding argument in the precedence order.

\item{\bull}
The :method-combination option is followed by a symbol or list, whose 
car is a symbol and crd is any arguments accepted by the method combination.
The symbol names a type of method combination.   Any arguments that follow 
that symbol depend on the type of method combination.   For example, all 
types of method combination defined by the short form of {\bf 
define-method-combination} accept an optional argument named {\it 
order\/}, defaulting to {\bf :most-specific-first}.  A value of {\bf
:most-specific-last} reverses the order of the primary methods, without
affecting the order of the auxiliary methods. 

\item{\bull}
The {\bf :documentation} argument is a string.

\item{\bull}
The {\bf :declare} argument is a list of declaration specifiers.

\item{\bull}
The {\bf :generic-function-class} argument is a class or the name of a class.

\item{\bull}
The {\bf :method-class} argument is a class or the name of a class.
\endlist


\label Values:

The result of {\bf make-generic-function} is a generic function object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function {\bf make-generic-function} is the
programmatic interface to {\bf defgeneric-options}.

\label See Also:

{\bf defgeneric-options}

\endcom

\begincom{make-instance}\ftype{Function}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defun {make-instance} {class {\rest} initialize-keywords-and-values}

\label Arguments:

The {\it class\/} argument is a class object or a symbol that names a class.

\label Values:

The new instance is returned.

\label Remarks:

[Discussion of initialization to go here.]

It is not possible to make an instance of a class whose class is
{\bf standard-type-class} using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf standard-type-class}, 
{\bf make-instance} signals an error.

%Removed because the :instantiable option was removed.  -Sonya
%If we put it back, note that the name of the option is changed. -Sonya 
%It is not possible to make an instance of a class created with {\bf
%defclass} if the {\bf :instantiable} option was {\bf nil}.  An error is
%signalled in this case. 

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

\label See Also:

{\bf class-of}

\endcom



\begincom{make-method}\ftype{Function}

\label Purpose:

The function {\bf make-method} creates and returns a method object.

\label Syntax:

\Defun {make-method} {method-qualifiers specializers function}

\label Arguments:

The {\it method-qualifiers\/} argument is a list of the method
qualifiers for the method.
%A method qualifier is a non-{\bf nil} symbol.

The {\it specializers\/} argument is a list of the parameter
specializers for the method.

The {\it function\/} argument is the method function.  

The length of the list of specializers must be equal to
the number of required arguments of the method function.

\label Values:

The function {\bf make-method} returns the resulting method object.
\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod

add-method}

\endcom


\begincom{make-method-call}\ftype{Function}

\label Purpose:

The function {\bf make-method-call} is used in method combination.  It
can be called only from the dynamic environment of a method combination 
function, that is, from the body of {\bf define-method-combination}, 
from a {\bf compute-effective-method} method, or from a function called
by one of these.

{\bf make-method-call} returns a form whose car is
the operator specified by the {\bf :operator} keyword argument
(default is {\bf progn}) and whose cdr is a list of forms that
call the methods in {\it method-list}.  Each method receives the same
arguments that the generic function received.  The function
{\bf make-method-call} hides the implementation-dependent details of
how methods are called.

\label Syntax:

\Defun {make-method-call} {method-list {\key :operator :around :identity-with-one-argument}}

\label Arguments:

Each element of {\it method-list\/} can be either a method object or a list.
When a list is given, it is regarded as a form and converted when necessary
into a method whose body is that form (conceptually by enclosing it in a 
lambda expression).
% Is there any clearer way to state this parenthetical remark?

If {\bf :around} is true and the length of {\it method-list\/}
is greater than 1, the result is a form that calls the first method and
arranges for {\bf call-next-method} to reach the rest of the methods in the
order in which they appear in {\it method-list}.  If {\bf :around} is 
true, {\bf :operator} must not be specified.  The default value of
{\bf :around} is {\bf nil}.

If {\bf :identity-with-one-argument} is true and {\it
method-list\/} contains exactly one element, the result is simply a
form that calls that single method and does not invoke the
operator.  If {\bf :operator} is {\bf progn}, the default for {\bf
identity-with-one-argument} is true; otherwise the default for this
option is false.  This option is to be used with operators that are
identity operators when applied to one argument, that is, such
operators as {\bf progn}, {\bf and}, {\bf $+$} and {\bf max}.  This
optimization can enable the use of an existing method as the
effective method, avoiding the need to create a new effective method.
The \OS's optimizer already knows about {\bf progn},
{\bf multiple-value-prog1}, and {\bf multiple-value-prog2}, but
{\bf :identity-with-one-argument} can be used to tell it about
other operators.

If {\it method-list\/} is {\bf nil}, the result is a call to
the specified operator with no arguments or a form with the same effect.

As a convenience, if {\it method-list\/} is a method object, it is
automatically converted to a one-element list of that method.

\vfill\eject
\label Values:

The result is a form whose car is the operator specified by the 
{\bf :operator} keyword argument and whose cdr is a list of forms
that call the methods in {\it method-list}.

\label See Also: 

See ``Declarative Method Combination''. 

\label Possible Extensions:

Additional keyword arguments will be needed if {\bf call-next-method}
is allowed to change the arguments passed on to the next method.  They
will be proposed separately. 

\endcom


\begincom{method-combination-error}\ftype{Function}

\label Purpose:

The function {\bf method-combination-error} reports a problem in method
combination.   The error message is constructed using a format string
and any arguments to it.  An implementation may add additional
contextual information to the error message, thus {\bf
method-combination-error} should be called only from the dynamic
environment of a method combination function.

The environment determines whether {\bf method-combination-error} returns
to its caller or throws.

\label Syntax:

\Defun {method-combination-error} {format-string {\rest} args}

\label Arguments: 

{\it format-string\/} is a control string that can be given to {\bf
format}, and {\it args\/} are any arguments required by the format
string. 

\label Remarks:

The function {\bf method-combination-error} will use the condition
signalling system when and if it is adopted into Common Lisp.

\label See Also: 

See ``Declarative Method Combination''. 

\endcom



\begincom{method-qualifiers}\ftype{Function}

\label Purpose:

The function {\bf method-qualifiers} returns a list of the qualifiers
of the given method.  This is particularly useful
when the body forms perform additional filtering or processing of the
method-group lists. 

% I don't understand sentence-2 here (i.e., what is meant by ``the body'').
% Is it possible to say: ``This function is particularly useful in
% filtering or processing method-group lists''?

\label Syntax:

\Defun {method-qualifiers} {method}

\label Arguments:

{\it method\/} is a method object. 

\label Values:

A list of the qualifiers of the given method is returned.

\label Examples:

\screen!

(setq methods (remove-duplicates methods
                                 :from-end t
                                 :key #'method-qualifiers
                                 :test #'equal))

\endscreen!

\label See Also: 

See ``Declarative Method Combination''. 

\endcom


\begincom{multiple-value-prog2}\ftype{Macro}

\label Purpose:

The macro {\bf multiple-value-prog2} is the obvious extension of 
{\bf multiple-value-prog1}.  It evaluates the given forms and returns
all the values of {\it result-form}. 

\label Syntax:

\Defmac {multiple-value-prog2} {form result-form \star{\curly{form}}}

\label Values:

All the values of {\it result-form\/} are returned.

\label See Also: 

See ``Declarative Method Combination''. 

\endcom




\begincom{print-object}\ftype{Generic function}

\label Purpose:

The generic function {\bf print-object} outputs the printed
representation of an object onto a stream.  The function {\bf
print-object} is called by the print system; it should not be called
by the user.

Each implementation is required to provide a default method for {\bf 
print-object}; that is, a method for the class {\bf t}.  Implementations 
are free to add methods for specific classes.  Users can write methods 
for {\bf print-object} for their own classes if they do not wish to 
inherit an implementation-supplied method. 

\label Syntax:

\Defgen {print-object} {object stream}

\label Arguments:

The first argument is any Lisp object.   The second argument is a
stream; it cannot be {\bf t} or {\bf nil}. 

\label Values:

{\bf print-object} returns its first argument, the object.  

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[This section needs to be rewritten.]

Methods for {\bf print-object} must obey the print control special
variables described in {\it Common Lisp the Language}.  The
specific details are:

*PRINT-ESCAPE*  Each method must implement this.

*PRINT-PRETTY*  This can be ignored by most methods other than the one for
                lists.

*PRINT-CIRCLE*  This is handled by the printer and can be ignored by
                methods.

*PRINT-LEVEL*   The printer takes care of this automatically, provided that
                each method handles exactly one level of structure and
                calls write (or an equivalent function) recursively if
                there are more structural levels.  The printer's decision
                of whether an object has components, and therefore should
                not be printed when the printing depth is not less than
                *PRINT-LEVEL*, is implementation-dependent.  In some
                implementations its PRINT-OBJECT method is not called, in
                others the method is called and the determination that the
                object has components is based on what it tries to output
                to the stream.

*PRINT-LENGTH*  Methods that produce output of indefinite length must obey
                this, but most methods other than the one for lists can
                ignore it.

*PRINT-BASE*, *PRINT-RADIX*, *PRINT-CASE*, *PRINT-GENSYM*, and
*PRINT-ARRAY* apply to specific types of objects and are handled by the
methods for those objects.

In general, the printer and the PRINT-OBJECT methods should not rebind the
print-control variables as they recurse through the structure, but this is
necessarily implementation-dependent.

In some implementations the stream argument passed to a PRINT-OBJECT method
is not the original stream, but is an intermediate stream that implements
part of the printer, so methods should not depend on the identity of this
stream.

All of the existing printing functions (write, prin1, print, princ,
pprint, write-to-string, prin1-to-string, princ-to-string, the format
{\tt ~}{\bf S} and {\tt ~}{\bf A} operations, and the format {\tt
~}{\bf B}, {\tt ~}{\bf D}, {\tt ~}{\bf E}, {\tt ~}{\bf F}, {\tt ~}{\bf
G}, {\tt ~}{\bf \$}, {\tt ~}{\bf O}, {\tt ~}{\bf R}, and {\tt ~}{\bf
X} operations when they encounter a non-numeric value) are required to
be changed to go through the PRINT-OBJECT generic function.  Each
implementation is required to replace its former implementation of
printing with one or more PRINT-OBJECT methods.  Exactly which classes
have methods for PRINT-OBJECT is not specified; it would be valid for
an implementation to have one default method that is inherited by all
system-defined classes.

References: See MIT AI Memo 816, December 1984, by Richard C. Waters for a
discussion of PP, one of the better designed Lisp printers.  It handles
*PRINT-LEVEL* and *PRINT-LENGTH* invisibly to the PRINT-OBJECT methods.
See also the inconclusive discussion on printing, *PRINT-LEVEL*, and
recursion on the Common-Lisp mailing list around 21 November 1985 for
additional background.

\endcom



%\begincom{remove-class}\ftype{}
%
%\label Purpose:
%
%\label Syntax:
%
%\Defun {remove-class} {class}
%
%\label Arguments:
%
%\label Values:
%
%\label Examples:
%
%\endcom



\begincom{remove-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf remove-method} removes a method from a generic
function.  It modifies the specified generic function and returns the
modified generic function as its result.
If this method is not a method of the generic function, an error is signalled.

\label Syntax:

\Defgen {remove-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument is either a generic function 
object; a symbol that names a generic function; or a list that names a
{\bf setf} generic function, such as ({\bf setf} {\it symbol\/}). 
An error is signalled if no such generic function exists. 

The {\it method\/} argument is a method object.  

\label Values:

{\bf remove-method} returns the modified generic function, which is the 
same object that was specified by the {\it generic-function\/} 
argument.  

%used to be:
%The result of {\bf remove-method} is the modified generic function. 

%method object with the given
%method qualifiers and parameter specializers.  If no such
%method object exists, {\bf remove-method} returns {\bf nil}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

\label See Also:

{\bf
get-method

add-method}

\endcom



%\begincom{remove-setf-method}\ftype{Function}
%
%\label Purpose:
%
%The function {\bf remove-setf-method} removes the {\bf setf} method
%for the given name, method qualifiers, and parameter
%specializers from the corresponding generic function.
%
%The method {\bf remove-setf-method} returns the given method object if it 
%succeeds and {\bf nil} if there is no such method.
%
%\label Syntax:
%
%\Defun {remove-setf-method} {generic-function method-qualifiers
%specializers setf-specializers}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is a generic function or the name
%of a generic function.
%
%The {\it method-qualifiers\/} argument is a list of the
%method qualifiers for the method.
%
%The {\it specializers\/} argument is a list of
%the parameter specializers for the arguments of the
%method that is to be removed.  If the {\it specializers\/}
%list contains fewer elements than the lambda list of the corresponding
%generic function, the remaining elements are considered to be {\bf t}.
%
%The {\it specializers\/} list can be obtained from a
%{\bf defmethod} lambda list by use of the function 
%{\bf lambda-list-specializers}.
%
%\label Values:
%
%The result of {\bf remove-setf-method} is the method object with the
%given method qualifiers and parameter specializers.  If
%no such method object exists, {\bf remove-setf-method} returns {\bf
%nil}.
%
%\label See Also:
%
%{\bf lambda-list-specializers
%
%remove-method
%
%defmethod}
%
%\endcom


\begincom{slot-value}\ftype{Function}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.   If there is no slot with that
name, an error is signalled. 

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot unless the slot is initialize-only.  Attempting to change the
value of an initialize-only slot causes an error to be signalled.

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Examples:

\screen!

[To be written.]
\endscreen!


\endcom


\begincom{with-slots}\ftype{Macro}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for referring to
slots as though they were variables.  Within such a context the value
of the slot can be specified by using its slot name, as if it were a
lexically bound variable.  Both {\bf setf} and {\bf setq} can be used
to set the value of the slot.  The macro {\bf with-slots} can be used
inside a method or inside of any function.

The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to the accessor generated by {\bf defclass}
unless the {\bf :use-accessors} argument is {\bf nil}. 

\label Syntax:  

\Defmac {with-slots} {\paren {\star{\curly{instance-form $\vert$ \paren{instance-form \star{option}}}}} \star{\form}}

{\it option\/}::$=$  {\tt\vtop{\hbox{:use-accessors {\it flag\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it prefix-string\/}}}}

\label Arguments:

The {\it instance-form\/} should evaluate to an object that has slots,
such as an instance of a user-defined class.   An instance of 
{\bf standard-type-class} does not have slots. 

Each {\it instance-form\/} is evaluated exactly once, upon entry to the 
body of the {\bf with-slots} form.  The {\it instance-form\/} forms 
are evaluated in the order in which they appear.  

It is necessary that the class of the instance can be determined.
Either {\it instance-form\/} must be the name of a specialized parameter in
the lambda-list of a method lexically containing this {\bf with-slots}
form, or the {\bf :class} option must be used to indicate the class of
the instance.

The keyword options in this special form are not evaluated.  These are
the keyword options:  

\beginlist

\item{\bull}
The {\bf :class} option is used to specify the class or a superclass
of the instance.  Its argument is the name of a class.  This option is
necessary if the class of the instance cannot be determined from the
lambda list of a method lexically containing the {\bf with-slots}
form or if the {\bf with-slots} form does not occur within a method
body.  If the {\bf :class} option is used an error is signalled if the
class of the instance is not a subclass of the specified class.

\item{\bull}
The {\bf :prefix} option is used to generate a variable name by which
the given slot may be referenced.
This name is given by {\it prefix-string\/} followed by the slot 
name.  It causes a symbol of the given name to be created and interned
in the package that is current at the time the {\bf with-slots} form is
macro-expanded. 
This option can be used to keep separate two instances whose slot names
overlap, such as two instances of the same class or two instances that
have a common superclass.

\item{\bull}
The {\bf :use-accessors} option is used to specify whether accessing a
slot is performed using the accessor function generated by {\bf defclass}
or by the function {\bf slot-value}.  If {\bf :use-accessors} is {\bf t},
the accessor function generated by defclass is used to access the slots; this
means that any methods written for the accessor are also run.
If {\bf :use-accessors} is {\bf nil}, {\bf with-slots} accesses the
slots using {\bf slot-value} instead of the accessor.
If accessors for the slot were not specified in the relevant {\bf defclass}
form, then the value of {\bf :use-accessors} should be specified as {\bf nil}.
The default value of {\bf :use-accessors} is {\bf t}.

\endlist

\label Values:

The value of the {\bf with-slots} form is the value returned by
the last form in its body. 

\label Examples:

\screen!

(defclass point () ((x 0) (y 0))
  (:accessor-prefix point-))

(defmethod move ((p point) dx dy)
  (with-slots (p)  ; p is known as a point from the method args
    (setf x (+ x dx) y (+ y dy))))       ; use accessor functions

(defmethod move ((p point) dx dy)
  (with-slots ((p :use-accessors nil))
    (setf x (+ x dx) y (+ y dy))))       ; use slot-value  
 
(defmethod make-same-height ((p1 point) (p2 point))
  ;; use :prefix to make distinction between the two points
  (with-slots ((p1 :prefix p1-) (p2 :prefix p2-))  
    (setf p1-y p2-y)))

(defmethod make-horizontal ((l line))
  ;; point is a component class of line
  ;; it is necessary to specify the class of point explicitly,
  ;; because there is no lexical way to determine it 
  (with-slots (((left-point l) :class point :prefix left-)
               ((right-point l) :class point :prefix right-))
    (setf left-y right-y)))
 
%(defmethod make-horizontal ((l line))
%   (let ((left (left-point l)) (right (right-point l)))
%     (with-slots ((left  :class point :prefix left-)
%                  (right :class point :prefix right-))
%       (setf left-y right-y))))

\endscreen!

\label Remarks:

The examples have used {\bf setf} to change the value of instance
variables; {\bf setq} is also allowed.  

An error is signalled if the class of {\it instance} cannot be inferred
from the lexical context in which it occurs.  

An error is signaled if there is any conflict between variable names. 

\endcom
\endChapter
\bye